Permission Matrix
AquaX — Role, Scope And Access Control
| Document Info |
|
| Version |
1.1 |
| Status |
Draft — Permission Baseline + Current Implementation Alignment |
| Created Date |
2026-09-17 |
| Last Updated |
2026-09-17 |
| Owner |
Product & Security |
| Reviewers |
Backend, Web, Mobile, QA |
| Source Documents |
03_SRS — Software Requirements Specification.md, 01-product/requirements/permission-matrix.md, 08-security/access-control.md, current backend/web/mobile route checks |
Implementation alignment note: This matrix defines the target product access model and calls out current implementation gaps. UI visibility is not sufficient; backend authorization must enforce every protected action.
Table of Contents
- Scope And Status
- Role Definitions
- Scope Model
- Permission Legend
- Product Permission Matrix
- Backend Enforcement Snapshot
- Web Access Snapshot
- Mobile Access Snapshot
- AI And Data-Scope Rules
- Critical Permission Gaps
- Test Requirements
- Traceability
- Document History
1. Scope And Status
This document covers role-level and scope-level permission requirements for:
- backend APIs;
- web routes and actions;
- mobile role navigation;
- reports and Excel export;
- notifications;
- IoT device control;
- Farming Handbook;
- future AI/chatbot context access.
Current status summary:
| Area |
Status |
Notes |
| Backend authentication |
PARTIAL |
Most module controllers use JwtAuthGuard; some use RolesGuard. |
| Backend role enforcement |
PARTIAL |
Role checks exist in several controllers/use cases, but many TEMPORARY BYPASS comments remain. |
| Backend farm/pond scope enforcement |
PARTIAL |
Scope logic exists, but bypasses remain in farm/pond/crop/log flows. |
| Web route access |
PARTIAL |
Current web private routes mainly expose ADMIN and OWNER; manager/technician web surfaces are limited or absent. |
| Mobile role navigation |
PARTIAL |
Mobile role enum is aligned with backend ADMIN, MANAGER, TECHNICIAN, OWNER; some owner-facing API/type names still use legacy Viewer* naming. |
| AI/chatbot authorization |
PLANNED |
No production chatbot context authorization exists yet. |
2. Role Definitions
2.1 Backend Canonical Roles
The current Prisma/backend role enum is:
| Role |
Meaning |
ADMIN |
System administrator with broad operational and configuration access. |
OWNER |
Farm owner/chủ hộ with access to owned or assigned farm context. |
MANAGER |
Manager role for operational management where implemented. |
TECHNICIAN |
Field or technical user assigned to ponds/tickets. |
2.2 Surface Naming Notes
| Surface |
Current Note |
| Backend |
Uses ADMIN, MANAGER, TECHNICIAN, OWNER. |
| Web |
Uses ADMIN and OWNER route guards in the current private route tree. |
| Mobile |
Uses backend-aligned ADMIN, MANAGER, TECHNICIAN, OWNER in mobile auth/user types. Legacy Viewer* names remain for owner-facing DTOs/hooks/endpoints where backend routes still expose viewer-style paths. |
| Documentation |
Uses Admin, Farm Owner, Pond Technician, Admin Technical Staff, and Viewer/Owner-facing user to describe business roles. |
3. Scope Model
| Scope |
Description |
Enforced By |
| System |
Full system access. Intended for ADMIN. |
Backend role checks and admin guards. |
| Farm |
Access to farm owned by or assigned to the user. |
Farm owner relation, farm membership and service checks. |
| Pond |
Access to assigned pond or pond under an accessible farm. |
Pond assignment, farm membership and service checks. |
| Ticket |
Access to created, assigned or scoped ticket. |
Ticket service filters and assignment checks. |
| Device/Sensor |
Access through pond/farm scope and explicit role/action permission. |
Device/sensor use-case checks, currently partial. |
| AI Context |
Access to authorized pond/farm data and approved knowledge only. |
Planned AI context builder and authorization layer. |
4. Permission Legend
| Symbol |
Meaning |
F |
Full access within product scope. |
R |
Read/view access. |
C |
Create access. |
U |
Update/process access. |
D |
Delete/archive/close destructive action. |
A |
Assign/reassign/configure access. |
S |
Scoped access only. |
- |
No access by default. |
P |
Planned or partial implementation. |
5. Product Permission Matrix
5.1 Module-Level Matrix
| Module / Function |
Admin |
Owner |
Manager |
Technician |
Admin Technical Staff |
Current Status |
| Login and profile |
R/U |
R/U |
R/U |
R/U |
R/U |
PARTIAL |
| User management |
F |
C/A for KTV within farm if enabled |
- |
- |
- |
PARTIAL |
| Farm management |
F |
R/U own farm as permitted |
R/S |
R/S |
R assigned context |
PARTIAL |
| Pond management |
F |
C/R/U own farm ponds |
C/R/U scoped ponds if enabled |
R assigned ponds |
R assigned context |
PARTIAL |
| Crop management |
F |
C/R/U own pond crops if enabled |
C/R/U scoped ponds if enabled |
R/input assigned pond context |
R assigned context |
PARTIAL |
| KTV assignment |
F |
A within owned farm if enabled |
A scoped if enabled |
- |
- |
PARTIAL |
| Water dashboard |
R all |
R own farms |
R scoped farms/ponds |
R assigned ponds |
R assigned ticket/pond context |
PARTIAL |
| Sensor management |
F |
R own farm if enabled |
R/U scoped if enabled |
R assigned if enabled |
R assigned context |
PARTIAL |
| Device management |
F |
R/U own farm if enabled |
R/U scoped if enabled |
R/U assigned if enabled |
R assigned context |
PARTIAL |
| Device remote control |
F |
U own farm if enabled |
U scoped if enabled |
U assigned if enabled |
U only if granted |
PARTIAL |
| Auto rules |
F |
A own farm if enabled |
A scoped if enabled |
- |
- |
PARTIAL |
| Alerts |
F |
R/U own farm alerts |
R/U scoped alerts |
R/U assigned pond alerts |
R/U assigned alerts/tickets |
PARTIAL |
| Feeding records |
F |
C/R/U own farm |
C/R/U scoped |
C/R/U assigned ponds |
R assigned context |
PARTIAL |
| Farming logs |
F |
C/R/U own farm |
C/R/U scoped |
C/R/U assigned ponds |
R assigned context |
PARTIAL |
| Reports and Excel |
F |
R/export own farm |
R/export scoped if enabled |
R/export assigned if granted |
R assigned context |
PARTIAL |
| Tickets |
F |
C/R own farm |
C/R/U scoped |
C/R assigned ponds |
R/U/D assigned tickets |
PARTIAL |
| Ticket assignment |
F |
- |
A scoped if enabled |
- |
- |
PARTIAL |
| Handbook reading |
R |
R |
R |
R |
R |
PARTIAL |
| Handbook administration |
F |
- |
- |
- |
- |
PARTIAL |
| Notifications |
R/U own notifications; admin configs |
R/U own |
R/U own |
R/U own |
R/U own |
PARTIAL |
| Notification configuration |
F |
- |
- |
- |
- |
PARTIAL |
| Activity/audit logs |
F |
R own farm scope if enabled |
R scoped if enabled |
- |
- |
PARTIAL |
| Settings/SLA/config |
F |
Limited farm threshold if enabled |
Limited scoped config if enabled |
- |
Technical config if granted |
PARTIAL |
| AI chatbot |
F/configure policy |
Use own farm context |
Use scoped context |
Use assigned pond context |
Use assigned ticket/pond context |
PLANNED |
| AI prediction/recommendation |
F/configure policy |
R own farm predictions |
R scoped predictions |
R assigned pond predictions |
R assigned context |
PLANNED |
5.2 Sensitive Action Matrix
| Action |
Admin |
Owner |
Manager |
Technician |
Current Enforcement Status |
| Create user |
Yes |
No, except KTV creation if explicitly enabled |
No |
No |
PARTIAL |
| Assign farm owner |
Yes |
No |
No |
No |
PARTIAL |
| Assign pond technician |
Yes |
Own farm if enabled |
Scoped if enabled |
No |
PARTIAL |
| Delete farm |
Yes |
Own farm if enabled |
No |
No |
PARTIAL |
| Delete pond |
Yes |
Own farm if enabled |
No |
No |
PARTIAL |
| Create/update/delete sensor |
Admin target |
No by default |
No by default |
No by default |
PARTIAL; bypass comments exist |
| Create/update/delete device |
Admin target |
No by default |
No by default |
No by default |
PARTIAL; bypass comments exist |
| Remote-control device |
Yes |
Scoped if enabled |
Scoped if enabled |
Assigned if enabled |
PARTIAL |
| Create/update/delete crop |
Admin/Manager target |
Scoped if enabled |
Scoped if enabled |
No by default |
PARTIAL; bypass comments exist |
| Close crop |
Admin/Manager target |
Scoped if enabled |
Scoped if enabled |
No by default |
PARTIAL; bypass comments exist |
| Override closed crop |
Admin target |
No |
No |
No |
PARTIAL; bypass comments exist |
| Edit/delete past farming logs |
Privileged target |
No by default |
No by default |
No by default |
PARTIAL; bypass comments exist |
| Configure SLA/settings |
Yes |
No by default |
No by default |
No |
PARTIAL |
| Approve/archive handbook article |
Yes |
No |
No |
No |
PARTIAL; bypass comments exist |
| Export all-system report |
Yes |
No |
No |
No |
PARTIAL |
| Access AI context outside scope |
No |
No |
No |
No |
PLANNED; must be prohibited |
6. Backend Enforcement Snapshot
6.1 Confirmed Patterns
| Pattern |
Evidence / Notes |
JwtAuthGuard |
Used across many controllers for authenticated API access. |
RolesGuard and @Roles(...) |
Used for reports, activity logs, settings, dashboard owner routes and some protected areas. |
| Admin-only settings |
settings.controller.ts uses @Roles(Role.ADMIN). |
| Owner dashboard |
dashboard.controller.ts uses @Roles(Role.OWNER) for owner dashboard endpoints. |
| Activity logs |
Controller exposes ADMIN and OWNER read paths, admin export path. |
| Farm/pond services |
Implement role and owner/scope checks in service/use-case code. |
6.2 Temporary Bypass Areas
The codebase currently contains TEMPORARY BYPASS comments in permission-sensitive areas. These must be resolved before production release.
| Area |
Examples |
| Admin guard / users |
Admin-only user API enforcement is temporarily bypassed in an admin guard. |
| Farm and pond scope |
Several farm/pond access-denial checks are temporarily bypassed. |
| Sensors |
Create/update/delete sensor admin-only checks are temporarily bypassed. |
| Devices |
Create/update/delete device admin-only checks are temporarily bypassed. |
| Crops |
Create/update/delete/close/override crop role checks are temporarily bypassed. |
| Farming logs |
Editing/deleting past records checks are temporarily bypassed. |
| Pond assignments |
Assign/unassign/reassign authorization checks are temporarily bypassed. |
| Handbook admin |
Admin-only action guard has temporary bypass. |
7. Web Access Snapshot
Current web route access is narrower than the product permission target.
| Web Area |
Current Route Role |
Notes |
| Owner dashboard |
OWNER |
Owner dashboard route exists. |
| User management |
ADMIN |
Admin route. |
| Farm management |
ADMIN |
Admin route. |
| Pond management |
ADMIN |
Admin route. |
| IoT devices |
ADMIN |
Admin route. |
| Reports |
ADMIN |
Admin route. |
| Tickets |
ADMIN |
Admin route. |
| Activity logs |
ADMIN |
Admin route. |
| Notifications |
ADMIN |
Admin route. |
| Settings |
ADMIN |
Admin route. |
| Manager web routes |
Not broadly exposed |
Product target remains partial/planned. |
| Technician web routes |
Not broadly exposed |
Product target remains partial/planned. |
Web navigation uses role-filtered shell items. Backend API authorization must remain authoritative.
8. Mobile Access Snapshot
Mobile currently has role-specific features and the mobile role enum is aligned with backend role values:
| Mobile Concept |
Current Notes |
ADMIN |
Admin user/farm surfaces exist in mobile code. |
TECHNICIAN |
Technician home, incidents, notifications/profile flows exist. |
MANAGER |
Manager role exists in mobile types and profile labels. |
OWNER |
Owner role is used by mobile auth, profile, admin user forms, filters and owner navigation. |
| Owner features |
Owner-style farm, feeding, farming logs, activity log and problem flows exist. Some DTO/hook/API constants keep legacy Viewer* naming for compatibility with existing backend routes. |
Required follow-up:
- Refactor legacy
Viewer* DTO/hook/API names to Owner* when backend route naming is also migrated.
- Confirm which mobile screens are supported for each backend role.
- Add permission tests for mobile route/action visibility where feasible.
9. AI And Data-Scope Rules
AI features are planned and must follow the same authorization model as reports and dashboards.
| Rule |
Requirement |
Status |
| AI context authorization |
AI context builder must filter by user role and farm/pond/ticket scope before model invocation. |
PLANNED |
| Handbook source control |
AI may use only approved handbook content and enabled sources. |
PLANNED |
| No cross-scope prompts |
User cannot ask about farms/ponds outside permitted scope. |
PLANNED |
| AI logging |
Prompt/context metadata/output/references/feedback/escalation must be logged according to privacy policy. |
PLANNED |
| Human fallback |
Serious or low-confidence AI outputs must suggest KTV/ticket fallback. |
PLANNED |
| Device safety |
AI must not directly execute device commands or critical operations. |
PLANNED |
10. Critical Permission Gaps
| Gap |
Risk |
Required Action |
| Temporary bypasses in backend permission checks |
Unauthorized data/action risk. |
Remove bypasses and add regression tests. |
Legacy mobile Viewer* owner-surface naming |
Naming can confuse maintainers even though auth role values now use OWNER. |
Rename DTO/hook/API labels after backend route migration or document as compatibility naming. |
Web exposes mostly ADMIN/OWNER |
Product target for manager/technician web flows is not represented. |
Confirm whether web manager/technician scope is required. |
| AI context auth not implemented |
Future AI may leak pond/farm data if not designed correctly. |
Implement AI authorization before AI context assembly. |
| Report/export scope must be verified |
Cross-farm data export risk. |
Add export scope tests. |
| Notification target is polymorphic |
User may receive inaccessible target link if checks are weak. |
Validate target authorization before display/open. |
| Device control permission is partially bypassed |
Unsafe device command risk. |
Enforce role/scope and audit every command. |
11. Test Requirements
11.1 Minimum Permission Regression Set
| Test ID |
Scenario |
Expected Result |
| PERM-001 |
Non-admin calls admin user management endpoint. |
Denied. |
| PERM-002 |
Owner requests another owner's farm. |
Denied. |
| PERM-003 |
Technician requests unassigned pond. |
Denied. |
| PERM-004 |
Non-admin creates/updates/deletes sensor. |
Denied unless explicitly granted. |
| PERM-005 |
Non-admin creates/updates/deletes device. |
Denied unless explicitly granted. |
| PERM-006 |
Unauthorized user sends device command. |
Denied and no command log created. |
| PERM-007 |
User exports report outside scope. |
Denied or scoped data only. |
| PERM-008 |
User opens notification target outside scope. |
Denied or target hidden. |
| PERM-009 |
User asks AI about unauthorized pond. |
Refused without data leak. |
| PERM-010 |
Non-privileged user edits/deletes past farming log. |
Denied. |
| PERM-011 |
Non-privileged user overrides closed crop. |
Denied. |
| PERM-012 |
Admin-only settings endpoint called by non-admin. |
Denied. |
11.2 Acceptance Rule
A role/scope feature is not production-ready until:
- backend denies unauthorized API access;
- web/mobile hides unavailable actions;
- direct API calls are denied;
- audit/activity logs exist for sensitive actions where required;
- tests cover positive and negative cases.
12. Traceability
| Area |
Reference |
| Business requirements |
02_BRD — Business Requirements Document.md |
| Software requirements |
03_SRS — Software Requirements Specification.md |
| Product permission baseline |
01-product/requirements/permission-matrix.md |
| Security access control |
08-security/access-control.md |
| Functional requirements |
01-product/requirements/functional-requirements.md |
| Acceptance criteria |
01-product/requirements/acceptance-criteria.md |
| Backend source |
backend/modules/**, backend/modules/auth/**, backend/modules/users/** |
| Web route source |
web/src/core/routes/private.tsx, web/src/core/constants/app-shell.ts |
| Mobile role source |
mobile/src/core/types/auth.types.ts |
| Documentation gaps |
DOCUMENTATION-GAPS.md |
13. Document History
| Version |
Date |
Author |
Changes |
| 1.1 |
2026-09-17 |
Product & Security |
Updated mobile role alignment from VIEWER to backend OWNER; retained legacy Viewer* naming note for DTOs/hooks/routes. |
| 1.0 |
2026-09-17 |
Product & Security |
Created root permission matrix from SRS baseline and current backend/web/mobile access-control review. |
End of Permission Matrix